<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta name="author" content="Basho Technologies" />
	<meta name="description" content="Webmachine request/response data" />
	<meta name="keywords" content="webmachine http rest web" />
    <meta http-equiv="content-type" content="text/html;charset=utf-8" />
	<link rel="stylesheet" href="css/style-1c.css" type="text/css" />
	<title>Webmachine request/response data</title>
</head>
<body>
	<div id="content">
		<h1><span class="hr"></span><a href="/">webmachine</a></h1>
		<ul id="top">
			<li><a href="/">Home</a></li>
			<li><a href="http://bitbucket.org/justin/webmachine/">Source Code</a></li>
                        <li><a href="contact.html">Contact</a></li>
		</ul>
		<div id="left">
<h3>Webmachine request/response data</h3>

<p>

This is documentation of the Webmachine Request Data API as embodied
by the <code>"wrq"</code> module.  This module is the means by which
resources access and manipulate the state of the request they are
handling.

</p>
<p>

Given that all webmachine resource functions have this signature:

</p>

<span class="fwf">f(ReqData, Context) -> {Result, ReqData, Context}</span>

<p>

we should explain in detail the <code>ReqData</code> input and output
parameter.  This is a data structure used to represent the request
sent by the client as well as the response being built by the
resource.  The <code>wrq</code> module is used to access the values in
the input parameter.  Most functions in most resources have no need to
modify the output <code>ReqData</code> and can simply pass along the
one received as input.  However, in some cases a resource will need to
make some update to the response other than that implied by
<code>Result</code> and in those cases it should use the
<code>wrq</code> module to build a modified <code>ReqData</code> from
the original one for the return value.

</p>
<p>

A couple of nonstandard types are assumed here:

</p>

<table><tr><th>Type</th><th>Description</th></tr>
<tr><td>string()</td><td>a list() with all elements in the ASCII range</td></tr>
<tr><td>rd()</td><td>opaque record, used as the input/output <code>ReqData</code></td></tr>
<tr><td>streambody()</td><td>A webmachine <a href="streambody.html">streamed body format</a></td></tr>
<tr><td>mochiheaders()</td><td>a structure used in mochiweb for HTTP header storage</td></tr>
</table>

<p>The accessors are:</p>

<table><tr><th>Function</th><th>Description</th></tr>
<tr><td><code> method(rd()) -&gt; 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'POST' | 'PUT' | 'TRACE' </code></td><td>The HTTP method used by the client.  (note that it is an <code> atom() </code>)</td></tr>

<tr><td><code> version(rd()) -&gt; {integer(),integer()} </code></td><td>The HTTP version used by the client.  Most often <code> {1,1} </code>.</td></tr>
<tr><td><code> peer(rd()) -&gt; string() </code></td><td>The IP address of the client.</td></tr>
<tr><td><code> disp_path(rd()) -&gt; string() </code></td><td>The "local" path of the resource URI; the part after any prefix used in <a href="dispatcher.html">dispatch configuration</a>.  Of the three path accessors, this is the one you usually want.  This is also the one that will change after <code>create_path</code> is called in your <a href="resources.html">resource</a>.</td></tr>

<tr><td><code> path(rd()) -&gt; string() </code></td><td>The path part of the URI -- after the host and port, but not including any query string.</td></tr>
<tr><td><code> raw_path(rd()) -&gt; string() </code></td><td>The entire path part of the URI, including any query string present.</td></tr>
<tr><td><code> path_info(atom(),rd()) -&gt; 'undefined' | string() </code></td><td>Looks up a binding as described in <a href="dispatcher.html">dispatch configuration</a>.</td></tr>

<tr><td><code> path_info(rd()) -&gt; any() </code></td><td>The dictionary of bindings as described in <a href="dispatcher.html">dispatch configuration</a>.</td></tr>
<tr><td><code> path_tokens(rd()) -&gt; list() </code></td><td>This is a list of <code> string() </code> terms, the disp_path components split by "/".</td></tr>

<tr><td><code> get_req_header(string(),rd()) -&gt; 'undefined' | string() </code></td><td>Look up the value of an incoming request header.</td></tr>
<tr><td><code> req_headers(rd()) -&gt; mochiheaders() </code></td><td>The incoming HTTP headers.  Generally, get_req_header is more useful.</td></tr>
<tr><td><code> req_body(rd()) -&gt; 'undefined' | binary() </code></td><td>The incoming request body, if any.</td></tr>

<tr><td><code> stream_req_body(rd(),integer()) -&gt; streambody() </code></td><td>The incoming request body in <a href="streambody.html">streamed</a> form, with hunks no bigger than the integer argument.</td></tr>
<tr><td><code> get_cookie_value(string(),rd()) -&gt; string() </code></td><td>Look up the named value in the incoming request cookie header.</td></tr>
<tr><td><code> req_cookie(rd()) -&gt; string() </code></td><td>The raw value of the cookie header.  Note that get_cookie_value is often more useful.</td></tr>

<tr><td><code> get_qs_value(string(),rd()) -&gt; 'undefined' | string() </code></td><td>Given the name of a key, look up the corresponding value in the query string.</td></tr>
<tr><td><code> get_qs_value(string(),string(),rd()) -&gt; string() </code></td><td>Given the name of a key and a default value if not present, look up the corresponding value in the query string.</td></tr>
<tr><td><code> req_qs(rd()) -&gt; [{string(), string()}] </code></td><td>The parsed query string, if any.  Note that get_qs_value is often more useful.</td></tr>

<tr><td><code> get_resp_header(string(),rd()) -&gt; string() </code></td><td>Look up the current value of an outgoing request header.</td></tr>
<tr><td><code> resp_redirect(rd()) -&gt; bool() </code></td><td>the last value passed to do_redirect, false otherwise -- if true, then some responses will be 303 instead of 2xx where applicable</td></tr>
<tr><td><code> resp_headers(rd()) -&gt; mochiheaders() </code></td><td>The outgoing HTTP headers.  Generally, get_resp_header is more useful.</td></tr>

<tr><td><code> resp_body(rd()) -&gt; 'undefined' | binary() </code></td><td>The outgoing response body, if one has been set.  Usually, append_to_response_body is the best way to set this.</td></tr>
<tr><td><code> app_root(rd()) -&gt; string() </code></td><td>Indicates the "height" above the requested URI that this resource is dispatched from.  Typical values are <code> "." </code>, <code> ".." </code>, <code> "../.." </code> and so on.</td></tr>

</table>


<p
>The functions for (nondestructive) modification of <code> rd() </code> terms are:
</p>


<table><tr><th>Function</th><th>Description</th></tr>
<tr><td><code> set_resp_header(string(),string(),rd()) -&gt; rd() </code></td><td>Given a header name and value, set an outgoing request header to that value.</td></tr>
<tr><td><code> append_to_response_body(binary(),rd()) -&gt; rd() </code></td><td>Append the given value to the body of the outgoing response.</td></tr>

<tr><td><code> do_redirect(bool(),rd()) -&gt; rd() </code></td><td>see resp_redirect; this sets that value.</td></tr>
<tr><td><code> set_disp_path(string(),rd()) -&gt; rd() </code></td><td>The disp_path is the only path that can be changed during a request.  This function will do so.</td></tr>
<tr><td><code> set_req_body(binary(),rd()) -&gt; rd() </code></td><td>Replace the incoming request body with this for the rest of the processing.</td></tr>

<tr><td><code> set_resp_body(binary(),rd()) -&gt; rd() </code></td><td>Set the outgoing response body to this value.</td></tr>
<tr><td><code> set_resp_body(streambody(),rd()) -&gt; rd() </code></td><td>Use this <a href="streambody.html">streamed body</a> to produce the outgoing response body on demand.</td></tr>
<tr><td><code> set_resp_headers([{string(),string()}],rd()) -&gt; rd() </code></td><td>Given a list of two-tuples of {headername,value}, set those outgoing response headers.</td></tr>

<tr><td><code> remove_resp_header(string(),rd()) -&gt; rd() </code></td><td>Remove the named outgoing response header.</td></tr>
</table>

		
		</div>
		<div id="footer">

		</div>
	</div>

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-4979965-5");
pageTracker._trackPageview();
} catch(err) {}</script>

</body>
</html>

